Copyright: Copyright © 2001-2002 Peganza


Introduction

Icarus is a utility program that analyzes your Delphi or Borland Pascal source code, and generates a Uses Report.

Icarus is a free super light version of our complete quality assurance product Pascal Analyzer, featuring 32 reports. Visit our website at  www.peganza.com for more information.

Icarus functions with Borland’s Pascal/Delphi compilers from BP7 and later:

Borland Pascal 7 (or earlier)

Delphi 1

Delphi 2

Delphi 3

Delphi 4

Delphi 5

Delphi 6

Delphi 7

Icarus parses your source code in the same way as Borland's compilers. It builds large data tables in memory and when the parsing is finished, produces a Uses Report.

Be forewarned that Icarus occasionally needs a lot of memory. The amount of memory needed is proportional to the number of code lines in the examined project.

See also:

How to use ICARUS.EXE
Known limitations

Main menu

Main window

Uses Report

__________________________________________________________

Copyright © Peganza 2001-2002. All rights reserved. All product names are trademarks or registered trademarks of their respective owners.

Web site: 	www.peganza.com

Email:	 	info@peganza.com


How to use ICARUS.EXE

Icarus is an easy to use standalone 32-bits Windows program. Just select a source file, a complete Delphi project (DPR-file), Delphi package (PKG-file) or a single source file (PAS-file), set a few options and start the analysis. Icarus presents the results either in a text viewer or in a HTML browser. The Uses Report is written to a text (*.txt) file.

You do not have to alter your code in order to examine it with Icarus. Icarus does not either change your code in any way.

Options that you select in Icarus are stored in an INI-file (ICARUS.INI) located in the program folder.

Follow this simple procedure to create the Uses Report:

1. Select a file, either a complete project or a single source file.

2. Make sure that the selected compiler target is suitable for the source code.

3. Press the Run button and wait from a few seconds till several minutes, depending on the size of the code
4. Examine the Uses Report with the built-in text viewer

As an alternative, you can start the Wizard to assist you in selecting code to analyze.

In order to make your source code possible to analyze with Icarus, you should make certain that only one statement exists for every source line, like

procedure Proc;

var

   I : integer;

begin

  ..

  I := 5;

  CallProc(I);

  ..

end;

..and not like

procedure Proc;

var

  I : integer;

begin

   ..

  I := 5; CallProc(I);

  ..

end;

Avoid the latter case, because ULA cannot decide if the identifier I is set or referenced first.

See also:

Introduction

Known limitations

Main menu

Main window

Uses Report


Main window

The main interface of Icarus consists of a menu, a toolbar, a viewer window, and a status bar. The toolbar provides speed buttons for common menu items.

Toolbar

The toolbar contains speed buttons for some of the menu selections.

Viewer

Icarus presents the Uses Report in a viewer window as a large read-only text block, which is also written to one or several files. The format is ordinary text.

Navigate in the text by scrolling or with the PgDn/PgUp keys.

The following commands are available in the viewer.

Down	Move the cursor down to the next line
Up	Move the cursor up to the previous line
Left	Move the cursor left one character
Right	Move the cursor right one character
Home	Move the cursor to the beginning of the line
End	Move the cursor to the end of the line
PgDn	Move to the next page
PgUp	Move to the previous page
Ctrl+Home	Move to the top of the text
Ctrl+End	Move to the bottom of the text
Ctrl+Shift+0-9	Set the position of bookmark 0-9 to the current position
Ctrl+0-9	Move to the previously set bookmark 0-9
Ctrl+C	Copy the selected text to the clipboard
Shift+Down	Extend the selection down one line
Shift+Up	Extend the selection up one line
Shift+Left	Extend the selection to the left one character
Shift+Right	Extend the selection to the right one character
Shift+Home	Extend the selection to the beginning of the current line
Shift+End	Extend the selection to the end of the current line
Shift+PgDn	Extend the selection down one page
Shift+PgUp	Extend the selection up one page

Status bar

The status bar presents different information, such as the current line number in the viewer.

See also:

How to use ICARUS.EXE

Introduction
Known limitations

Main menu

Uses Report


Main menu

¨

The main menu has six submenus.

File menu

Edit menu

Search menu

Analysis menu

Options menu

Help menu

See also:

How to use ICARUS.EXE
Introduction
Known limitations

Main window

Uses Report


File menu

File|Open (Ctrl+O)

Select either a single source file for analysis, or an entire Delphi project (DPR-file), or an entire Borland Pascal project (PAS-file). You may also select a Delphi package (DPK file).

Icarus scans the selected source file. Any units specified in the uses statement of a unit, will be read, if they are found. This is a recursive process, and potentially a lot of source code can be involved. For Delphi source code, if a DFM-file is found for a PAS-file, the DFM-file will be parsed and examined as well.

If Icarus finds any include directives (like {$I MYSOURCE.INC}) in the source code, these files will also be read and parsed.

Even if Icarus can detect many syntax errors, it is required that the code is possible to compile. Otherwise, the results may be incorrect and possibly misleading. So, as a rule, always make sure that the code compiles, before examining it with Icarus.

Also remember, that the memory consumption and the time needed to parse and produce the Uses Report is proportional to the amount of source code.

File|Run Wizard

Run the Wizard.

File|Print (Ctrl+P)

Print the Uses Report.

File|Printer setup

Show Windows standard printer setup dialog box.

File|Exit

Quit the application.

See also:

Main menu

Uses Report


Edit menu

Edit|Copy (Ctrl+C)

Copy the selected text to the clipboard. Please observe that a maximum of 64K can be copied to the clipboard. If the data amount exceeds that value, an error message is shown and the operation is cancelled.

Edit|Select all (Ctrl+A)

Select all text in the viewer.

See also:

Main menu

Uses Report


Search menu

Search|Find (Ctrl+F)

Search for a string in the viewer text.

Search|Search again (F3)

Repeat the last search.

Search|Go to Line Number (Ctrl+G)

Select a line number, and move to that line.

See also:

Main menu

Uses Report


Analysis menu

Analysis|Run (Ctrl+R)

Start the analysis and produce a Uses Report.

Analysis|Stop

Stop (interrupt) the analysis. Please observe that it may take a few seconds until the analysis stops.

See also:

Main menu

Uses Report


Options menu

Options|Properties

Select properties for Icarus. The properties are spread over three tab pages.

Properties - General

Properties - Parser

Properties - Switches

Click OK to confirm your selections and return to the main window.

Options|Viewer font

Select a non-proportional font for the viewer window.

Default = Courier New 10 pt, black color

Options|Viewer color

Select a background color for the viewer window.

Default = White

Options|Show toolbar

Mark this menu item if you want the toolbar to appear.

Default = Yes

See also:

Main menu

Uses Report


Help menu

Help|Contents

Displays the help system.

Help|Visit Peganza on the Internet

Opens Peganza's home page in your web browser. Read the latest information about Icarus, Pascal Analyzer and our other products.

Help|About

Displays the application’s About dialog box.

See also:

Main menu

Uses Report


Uses Report

This report section lists all units that Icarus is able to find. For each unit, the uses statements are analyzed. The units specified in these clauses are listed, indicating if they are actually used.

Removing unused uses references has multiple benefits:

- cleaner code to maintain, no need to bother about code that is not used

- code from initialization and finalization sections in unused units is not linked in and run, reducing the size of the EXE

- compilation runs smoother and quicker

Units specified in the interface uses list are categorized as:

Unnecessary

Used in unknown way

Used in interface

Used in implementation

You can probably remove units categorized as “unnecessary” from the uses list. If they are categorized as “used in implementation”, move them to the uses list in the implementation section.

Units specified in the implementation uses list are categorized as:

Unnecessary

Used in unknown way

Used in implementation

You can probably remove units categorized as “unnecessary” from the uses list.

A special case is Delphi project files (DPR-files). The units listed in the uses list in the DPR-file are often not referenced in that file, and ULA consequently categorizes them as unnecessary. Nevertheless, you probably want to keep them in that uses list, so they are available to Delphi’s Project Manager.

When you drop a VCL component on a Delphi form the Delphi IDE automatically adds the unit or units required by the component to the interface section uses statement. Even if you later remove the component, the units are not deleted from the uses statement. This causes the need to sometimes clean the uses statement of unused units. In addition, units that you add manually may be left behind in the uses statements if you later delete the code sections that need these units.

Even if the compiler does not include code from units that are never used, the initialization section (or finalization section) is included in the EXE file regardless of whether any methods from the unit are used or not. The initialization section is also always executed when the application starts. This is a good reason why you should remove superfluous units from the uses lists. It will also make compilations more efficient. The fewer units in the uses clause, the quicker the compiler can do its job.

Sometimes, Icarus determines hat a unit is not needed, but Delphi reinserts it anyway into the uses-list when the unit is saved. This happens when working in the Delphi IDE.

If a project uses conditional compilation, maybe a unit is sometimes needed and sometimes not; such a unit must remain within a project. You could wrap conditional defines around such a unit declaration in the uses clause, like:

uses

   Common, (*$IFDEF Special*) Spec, (*$ENDIF*), Utils;

See also:

Main menu


Properties - General

Report Folder

Specify the folder where Icarus will write the Uses Report (text file format) upon completion of the analysis.

The default folder is the folder where the application program file (ICARUS.EXE) is stored. You probably want to select another folder to keep the report files separated from the Icarus program files.

The file is named MYPROG.TXT when MYPROG is examined. If the backup option is selected and a file with the same name exists, this file is saved under the name MYPROG.~XT.

See also:

Options menu

Properties - Parser

Properties - Switches

Uses Report


Properties - Parser

Target version

Select the compiler version targeted for the current analysis. Note that, although Icarus scans the source files in the same way as the compiler, it does not detect every syntax error. Make sure that the source code compiles correctly for the specified target, otherwise the results output by Icarus may be incorrect.

Icarus supports code written for these compilers:

- Borland Pascal 7 (16-bits)

- Delphi 1 (16-bits)

- Delphi 2 (32-bits)

- Delphi 3 (32-bits)

- Delphi 4 (32-bits)

- Delphi 5 (32-bits)

- Delphi 6 (32-bits)

- Delphi 7 (32-bits)

Default = Delphi 7

Icarus may also work with earlier versions of Turbo Pascal (prior to Borland Pascal 7), but this has not been validated and consequently is not guaranteed. In this case, select Borland Pascal 7 for best results.

For targets Delphi 1 and upward, Icarus is able to preload identifiers from the System unit in Delphi's runtime library. This makes Icarus aware of subprograms like Inc and FreeMem.

Include files must exist

Mark this checkbox if a missing include file should trigger an error and stop the analysis. Keep this option selected if possible, since a vital missing include file could generate incorrect results.

Default = Yes

Use Delphi project options if found, and merge with settings in this dialog

When a Delphi compiler and a DPR file is selected, Icarus tries to load the corresponding project options file (CFG file in Delphi 4 or higher, DOF file in Delphi 2 and 3, and OPT file in Delphi 1). If successful, these options are used. For search paths, unit aliases and defines, the options are merged with the options you select. This makes it possible to instance, in Icarus to provide the path to the VCL source files.

If a Delphi project file (DPR file) is parsed, search paths following the in keyword are automatically followed.

Search folders

Select the drives and folders where Icarus will search for source files. The folder containing the primary source file is automatically searched, and there is no need to include this folder.

Unlike the compiler, Icarus does not require that all source code is available. However, it is often best to make as much source code available to Icarus as possible.

Enter search folders, in priority order, separated with a semicolon e. g.:

c:\source\myunits;c:\source\generic;c:\source\proj1

You may also enter relative paths, like “..\..\generic”.

Alternatively, press the ellipsis button to select the folders in a selection dialog.

Unit aliases

Select unit aliases (Delphi 2 and upwards).

Default = WinTypes=Windows;WinProcs=Windows;DbiTypes=BDE;DbiProcs=BDE;DbiErrs=BDE

See the Delphi documentation for an explanation of unit aliases.

Conditional defines

Specify conditional compilation directives that are valid for the current analysis. Icarus parses source code just like the compiler, and must treat conditional directives, meaning that it will ignore sections of not activated code. You may also include defines within the source code.

Enter conditional defines, separated with a semicolon e. g.:

Final;Special

Alternatively, press the ellipsis button to enter the defines in a dialog box.

Icarus even initializes predefined defines just as the compiler does (e g 'WIN32'). It also keeps track of the state of all compiler directives so that directives like {$IFOPT} will function correctly.

Expressions for $IF-directives, that evaluate to TRUE

In Delphi 6, the new $IF-directive was introduced. The $IF-directive is followed by an expression, that evaluates to TRUE or FALSE. If you use $IF-directives, you must supply all expressions that evaluate to TRUE, because Icarus cannot always determine the value of an expression. Enter the expressions separated with semicolons, like:

Defined(WIN32) and (RTLVersion > 14);Declared(Windows)

The above expression is by the way appropriate when parsing cross-platform code (code used for both Windows and Linux).

When Icarus' parser finds a $IF-directive in code, it will try to evaluate it. If it is an expression that you have supplied, it will be evaluated to TRUE, otherwise it will be evaluated as FALSE. Directives that are evaluated as FALSE, means that the corresponding code is not activated.

See also:

Options menu

Properties - General

Properties - Switches

Uses Report


Properties - Switches

On this tab, you can select which compiler switches that are current for the analysis. This is important for how Icarus evaluates $IFOPT directives. For instance, if $R+ (range check) is activated, a directive {$IFOPT R+} will evaluate to TRUE, and the following code is activated.

A better method than setting these switches is to maintain a common include file used by all your modules. The purpose of the file is to set compiler directives and conditional defines that govern the compilation (and parsing by Icarus). The include file directive $I is used to embed the contents of the include file into the source files.

See also:

Options menu

Properties - General

Properties - Parser

Uses Report


Selection dialog

In this dialog box, select items and add them to a list. For instance, to add a search folder, enter the path in the input field below the list box. Then press the Add-button to add the folder to the list. Click on the ellipsis button to select a folder by browsing.

See also

Properties - Parser

Uses Report


Known limitations

There are situations that Icarus currently cannot handle very well. Some of them, but certainly not all, are:

1. When overloaded subprograms are referenced in code, Icarus does not try to figure out which one of the possible subprograms that is actually called. None of them are registered as referenced in this case.

Example:

procedure Proc(I : integer); overload;

procedure Proc(I : longint); overload;

procedure Proc(I : longint; S : string); overload;

..

..

if X then

  Proc(Num);

In this case, the call to Proc is not resolved, and none of the possible procedures are registered as referenced.

2. Objects that are created through a class reference cannot be resolved. The actual class is determined at runtime.

Example:

type

  TMyClassRef = class of TMyClass;

  TMyClass = class

    ..

    procedure Method; virtual;

  end;

  TMyDerivedClass = class(TMyClass)

    ..

    procedure Method; override;

  end;

..

procedure Proc(C : TmyClassRef);

begin

  C := TMyClassRef.Create; // TMyClass or TMyDerivedClass?

  C.Method; // TMyClass.Method or TMyDerivedClass.Method?

  ..

end;

3. Methods that are marked as abstract in a base class and used in that class, cannot be resolved:

Example:

type

  TBase = class

  ..

    procedure Main;

    procedure Proc; virtual; abstract;

  end;

  TDesc = class(TBase)

  ..

    procedure Proc; overload;

  end;

  TAnotherDesc = class(TBase)

  ..

    procedure Proc; overload;

  end;

  procedure TBase.Main;

  begin

    ..

    Proc; // which one, TDesc.Proc or TAnotherDesc.Proc?

  end;

The actual usage of Proc is determined at runtime.

4. Assert calls are not excluded from the parsing process, unlike in Delphi, regardless if the $C- setting is active or not. This means that identifiers used in the Assert procedure call, will be registered, and appear in the reports.

Example:

procedure MyProc(P : pointer);

begin

  Assert(P <> nil);

  ..

end;

The parameter P will be registered and appear in the reports. When compiled by Delphi, this code line will be stripped out if $C- is defined.

See also:

Introduction

How to use ICARUS.EXE

Main menu

Main window

Uses Report


Wizard

The Wizard guides you through the process of selecting a Delphi project or a unit file for analysis. It also allows you to set all important parameters for the analysis. For full control over all parameters, select the Properties dialog. When the Wizard finishes, the analysis starts and a Uses Report is produced.

You can choose to show the Wizard each time Icarus is started.

See also:

Main menu

Uses Report